ADFS SAML Setup

Active Directory Federate Services (ADFS) is the SAML provider that comes with Microsoft Active Directory. The following guide is to help the deployment of an ADFS SAML configuration as the authentication provider for Pyramid.

Important: If Same Site client security is set to Strict when using SAML authentication, this may cause a loop redirect between Pyramid and the SAML provider, as cookies are prevented from working across different web domains. This shouldn't be an issue if your SAML provider and Pyramid are within the same web domain.

Setup in ADFS

Step 1: Connect to ADFS

Connect to your local ADFS.

Step 2: Coinfigure ADFS

Open ADFS Management:

  1. Go to Relying Party Trusts. Click Add Relying Party Trust and add your Pyramid URL.

    For details about creating a relying party trust, click here.

  2. Select the Pyramid URL from the list of Relying Party Trusts. Go to the Identifier tab, add the Pyramid URL as the Display name and Relying party identifiers.
  3. Click the Endpoints tab. Click Add SAML and set binding as POST and Trusted URL as https://www.pyramidanalytics.com/login/callback
  4. Right-click on the Pyramid URL and select Edit Claim Rules. Set a rule to match a value to the subject token. This value should be the principal name.

Step 3: Export the ADFS Signing Certificate

Export the ADFS Signing certificate to a file. The contents of the file will must be pasted into the Pyramid ADFS SAML configuration settings later on.

Step 4: Update Web.Config

Important: You must make this update on all Pyramid web servers that are running IIS.

An additional setting in IIS must be configured. By default, the web.config file can be found in the following location on all Pyramid web servers running IIS:

"C:\program files\pyramid\repository\iis\web.config"

Change your web.config file to the following:

<?xml version="1.0" encoding="UTF-8"?> <configuration> <system.webServer> <security> <requestFiltering> <requestLimits maxAllowedContentLength="2147483648" /> </requestFiltering> </security> <rewrite> <rules> <rule name="ReverseProxyInboundRule1" stopProcessing="true"> <match url="(.*)" /> <action type="Rewrite" url="http://localhost:8181/{R:1}" /> </rule> </rules> <outboundRules> <rule name="302" preCondition="302"> <match serverVariable="RESPONSE_Location" pattern="(.*)#redirect=(.*)" /> <action type="Rewrite" value="{R:2}" /> </rule> <preConditions> <preCondition name="302"> <add input="{RESPONSE_STATUS}" pattern="3[0-9][0-9]" /> </preCondition> </preConditions> </outboundRules> </rewrite> <defaultDocument> <files> <clear /> <add value="readme.html" /> </files> </defaultDocument> </system.webServer> </configuration>

Step 5: Copy the Signature File

Open the Signature file that you exported at Step 3 and copy it.

Setup in Pyramid

Step 6: Capture SAML Settings

Open Pyramid and go to the Admin console:

  1. From the main menu, click Security > Authentication.
  2. From the Provider drop-down, select SAML.

In the SAML Settings panel (blue arrow) in Pyramid, enter the following details as per the general SAML setup.

The details that are specific to ADFS are:

  • Vendor: Select ADFS.
  • Certificate (Base64): Copy and paste the certificate that was exported during Step 3 into this field.

Step 7: Create Initial User

Enter the initial user details as explained here:

  • User Name: The internal user name of the initial user. This is a bypass for the user when working outside of SAML.
  • First Name: The first name of the initial user.
  • Last Name: The last name of the initial user.
  • Email: The email of the initial user.
  • Principal Name: The SAML login ID of the initial user typically in the format someone@domain.com. This is the critical element that will enable Pyramid to match the incoming SAML assertion with the user account.
  • Password: The internal password for the user. Only used if manually logging in without the SAML framework.

    • Tip: To login manually, you can use the /login/login.html or just /login entrypoints.

Get your Principal Name

  1. Click Test.

    2. A request is sent to the ADFS URL.

  2. Login to Pyramid ADFS.

    3. You will see a page with the message "System isn't configured to SAML."

  3. Copy the domain name from the subject field and paste it under Principal Name in Pyramid.

Step 8: Save your changes

There are two options for saving your changes:

  • Click Save to update the current settings.
  • Click Apply to change vendor / provider completely. This action will delete or disable all users.

If you click Apply, you are prompted to select Disable from the Delete / Disable Users dialog and click OK. Once you have made your selection, the browser will ask you if you want to leave the site; select Leave. You will be directed to your ADFS login page.

Step 9: Login

Login with your ADFS organizational account. You will be directed to the Pyramid application.